Introducing Bonz's HUGI formatting system :-)

Bonz

Well, maybe this is a bit of a bombastic name for two humble sed scripts that I am presenting. sed is the Unix stream editor, a very simple (yet very powerful) scripting language used to put together all kinds of filters. You can find my sed site at http://pcsiwa.rett.polimi.it/~paolob/seders/, it includes my own version of the program which is called super-sed. Anyway, none of the super-sed features are used in the scripts I present so you can use a standard version if you already have one.

What is Bonz's HUGI formatting system?

This is simply a way to format articles so that you can easily convert them to Hugi's internal format, and two scripts that do the conversion. I have found this very useful when contributing to Hugi 23 and 24.

In practice, this factors away most of the differences between Hugi's markup language and HTML. The idea is that this will save some work to either you (in case you were sending properly formatted markup) or Adok (in case you were sending text or HTML), resulting in better editing and proofreading, and an overall better quality of the magazine.

I wrote two scripts, one for articles that scroll vertically and have a one-column layout, such as coding articles, and the other for articles with a two-column layout, such as demoscene news and rants.

The text to be passed to the system is composed of paragraphs. Paragraphs are separated by a newline (like TeX if you ever used it), and two or more newlines indicate that the following paragraph is a headline. For example:

    This is a paragraph This is a paragraph This is a paragraph
    This is a paragraph This is a paragraph This is a paragraph
    This is a paragraph This is a paragraph This is a paragraph
    
    This is another paragraph This is another paragraph 
    This is another paragraph This is another paragraph 
    
    
    This is a headline
    
    This is another paragraph This is another paragraph 
    This is another paragraph This is another paragraph 
    
    
    This is another headline
    
    This is another paragraph This is another paragraph 
    This is another paragraph This is another paragraph 

The first line is special, because it contains the author and his (optional) e-mail address. For example:

    Sines and cosines for fun and profit - Bonz (bonzini@gnu.org)

or

    Dialogos 2001 report - Tomcat / Greenroom

You can also insert images with a special placeholder composed of four < signs:

    <<<< here goes sc-sincos.bmp >>>>

Images can be given have a caption like this

    <<<< image dialogos2001b.jpg (a caption...) >>>>

The file name must be right before the closing markup or the parenthesized caption, the rest is ignored (like "here goes" or "image" above). Two images can be put one next to each other (like on the option page) by putting two such placeholders one next to each other.

The last feature common the two scripts is the signature. A line made of "--" only starts a signature that goes on until the end of the file:

    Have fun!
    
    --
    |_  _  _ __
    |_)(_)| ),'
            `-._

and if no such line is found the very last line is always treated as a signature:

    I can summarize that Dialogos 2001 was one of the best parties
    of my life, and I am sure I will save my last pennies to visit again
    next year. However, I could imagine some improvements on the
    over-technocratized compo management system, which only
    accepted entries on the local network, which we were unable
    to connect to. But still, Dialogos deserves 9 points out of 10,
    losing that one only because of the compo entries' overall quality.

    tomcat^grm

These features are common to the two scripts. In addition, the one-column script supports enclosing code, that must be indented by four spaces: code is automatically put in the correct color and preformatted (that is, line ends are preserved like in the HTML <pre> tag). The two-column script's special feature instead is that image placeholders need not occupy a separate paragraph (which is often needed to achieve correct placement of images).

Some more details

Now here are some details on the Hugi markup so that you can add some bells and whistles to your articles. There are a few tags that are identical to HTML: these are <b>, <i>, <font>. However the <font> tag is much more powerful and can assign predefined styles to your text: of particular importance is the code style, which can be used to embed code or other monospaced text in a paragraph.

Examples:

    This is <font style code>some-&emp;gt;code</font>.
    This is Greek: <font face="Symbol">wxyz</font>.
    This is <font color=FF0000>red</font>.
    This is <b>bold </b> and this is <i>italic </i>.

You have to use entities like in HTML: &emp;emp; (not &emp;amp; like HTML!!!) is for the ampersand, &emp;lt; is for the less-than sign, and &emp;gt; is for the greater-than sign. The scripts do not convert < > &emp; to the corresponding entities in any case, not even in code blocks (it is often useful to add tags inside code blocks, for example to mark pseudocode as italic). The parser is somewhat permissive about them, so it's not hard to get things right.

Finally, the markup for hyperlinks is completely different from HTML: it is <link external="URL">some text</link>. I guess that this is enough. Now...

Script 1: vertical scrolling, one-column (tutorials and literature)

#! /bin/sed -nf

# On the first line, produce the heading
1 {
  /)$/! s/$/ ()/
  s/^\(.*\) - \(.*\) (\(.*\))$/<article scheme=default title="\1" author="\2">\
\
<p align=c fl=0>\
<font style=headline_def>\
\1\
<\/font>\
<p>\
<i>\
<link external="mailto:\3">\
\2\
<\/link>\
<\/i>\
\
<p align=j spacing=13>/
  s/\(author="[^"]*\)\/[^"]*/\1/
  s/ *"/"/g
  
  /mailto:"/ {
    s/<link external="mailto:">\n//
    s/<\/link>\n//
  }
}

# Print a heading, and skip the blank lines after it
# Print the first <p> tag (from hold space) if any
:heading
p
n
:skip
n
/^$/ {
  p
  bskip
}

# Process a paragraph
:paragraph

# Special paragraph -- signature
/^--$/ {
  s/^/<p align l>\
<font style code>\
<pre>/
  :loop
  p
  $a\
</pre>\
</font>
  n
  bloop
}

# Special paragraph -- image
/^ *<<<</! {
  x
  /./ p
  s/.*/<p>/
  x
}

:line
# In the following line the first two slashes enclose a TAB
s/	/        /g

# One line sig
$s/.*/<br>\
<p fl 0 align r>\
<b>\
&emp;\
<\/b>/


# Convert images.  The next paragraph must be centered,
# and placeholders must be changed to <image> tags.
/^ *<<<</ {
  i\
<p align c>
  s/<<<<[ a-z]* \([a-z0-9_-]*\....\) >>>>/<image file \1 right 8>/g
  s/<<<<[ a-z]* \([a-z0-9_-]*\....\) (\([^)>]*\)) >>>>/<link desc "\2">\
<image file \1 right 8>\
<\/link>/g
  s/\(.*\) right 8>/\1>/
  x
  s/.*/<p align j>/
  x
}

# Convert code.  Empty lines are collapsed and they are
# treated as code if they are followed by other code.
/^    / {
  s/^/<font style code>\
<pre>/
  :code
  p
  n
  # In the following line the first two slashes enclose a TAB
  s/	/        /g
  /^   /bcode
  /^$/ {
    :eat
    n
    /^$/ beat
    # In the following line the first two slashes enclose a TAB
    s/	/        /g
    /^    / {
      i\

      bcode 
    }
  }

  i\
</pre>\
</font>\

  bparagraph
}

# If the line is not empty, go on with the next one.
/^$/! {
  p
  n
  bline
}

# Print the blank line.  If it is not a heading marker
# (two blank lines) start a new paragraph
:blank
p
n
/^$/! bparagraph

# Skip further blank lines
:skip1
p
n
/^$/ bskip1

# Insert a heading tag
s/.*/<p align=j spacing=14>\
<font style subheadline_def>\
&emp;\
<\/font>\
/

# Set up the spacing attribute for the next paragraph
x
s/>/ spacing 16>/
x
  
# Print a heading, and skip the blank lines after it
# Then print the 

tag and process the next paragraph bheading

Script 2: horizontal scrolling, two-column (reports and opinions)

#! /bin/sed -nf

# On the first line, produce the heading
1 {
  /)$/! s/$/ ()/
  s/^\(.*\) - \(.*\) (\(.*\))$/<article scheme=columns title="\1" author="\2">\
\
<p align=c fl=0>\
<font style=headline>\
\1\
<\/font>\
<p>\
<i>\
<link external="mailto:\3">\
by \2\
<\/link>\
<\/i>\
\
<p align=j spacing=11>\
/
  s/\(author="[^"]*\)\/[^"]*/\1/
  s/ *"/"/g
  /mailto:"/ {
    s/<link external="mailto:">\n//
    s/<\/link>\n//
  }
  p
  x
  s/.*/<p fl 0 spacing 0>/
  x
  d
}

# Process a paragraph
:paragraph

# Special paragraph -- signature
/^--$/ {
  s/^/<p align l>\
<font style code>\
<pre>/
  :loop
  p
  $a\
</pre>\
</font>
  n
  bloop
}

# Special paragraph -- image: no first line indent
/^ *<<<</ {
  x
  / fl/ s/ fl [0-9]*/ fl 0/
  / fl/! s/>/ fl 0>/
  x
}

x
p
s/ spacing 0//
s/ fl 12//
s/ fl [0-9]*/ fl 12/
x

:line
# In the following line the first two slashes enclose a TAB
s/	/        /g

# One line sig
$s/.*/<br>\
<p fl 0 align r>\
<b>\
&emp;\
<\/b>/

# Convert images.  The next paragraph must be centered,
# and placeholders must be changed to <image> tags.
/^ *<<<</ {
  s/<<<<[ a-z]* \([a-z0-9_-]*\....\) >>>>/<image file \1 top 4 bottom 5>/g
  s/<<<<[ a-z]* \([a-z0-9_-]*\....\) (\([^)>]*\)) >>>>/<link desc "\2">\
<image file \1 top 4 bottom 5>\
<\/link>/g
  x
  / fl/ s/ fl [0-9]*/ fl 0/
  / fl/! s/>/ fl 0>/
  x
}

# If the line is not empty, go on with the next one.
:printline
p
n

# Convert in-paragraph images
/^ *<<<</ {
  s/<<<<[ a-z]* \([a-z0-9_-]*\....\) >>>>/<image file \1>/g
  s/<<<<[ a-z]* \([a-z0-9_-]*\....\) (\([^)>]*\)) >>>>/<link desc "\2">\
<image file \1>\
<\/link>/g
  i\
<brs>\
\
<p fl 0>
  a\
\
<p fl 0>
  x
  / fl/! s/>/ fl 12>/
  x
  bprintline
}

/^$/! bline

# Else skip further blank lines and start a paragraph
p
:blank
n
/^$/bblank
bparagraph

How to use the scripts

This is very easy. Just do

    sed -nf script-name.sed source > destination

The scripts can be extracted from the magazine. Just save this article to HTML (F2), open it in the browser and do cut&emp;paste in Notepad.

Have fun, and contribute to HUGI!

--
|_  _  _ __
|_)(_)| ),'
        `-._